# Webpack

This section introduces how to migrate a project using webpack to Rsbuild.

## Installing Dependencies

First, you need to replace the npm dependencies of webpack with Rsbuild's dependencies.

import { PackageManagerTabs } from '@theme';

- Remove webpack dependencies:

<PackageManagerTabs command="remove webpack webpack-cli webpack-dev-server" />

- Install Rsbuild dependencies:

<PackageManagerTabs command="add @rsbuild/core -D" />

## Updating npm scripts

Next, you need to update the npm scripts in your package.json to use Rsbuild's CLI commands.

```diff title="package.json"
{
  "scripts": {
-   "serve": "webpack serve -c webpack.config.js",
-   "build": "webpack build -c webpack.config.js",
+   "dev": "rsbuild dev",
+   "build": "rsbuild build"
  }
}
```

## Create Configuration File

Create a Rsbuild configuration file `rsbuild.config.ts` in the same directory as package.json, and add the following content:

```ts title="rsbuild.config.ts"
import { defineConfig } from '@rsbuild/core';

export default defineConfig({
  plugins: [],
});
```

> See [Configure Rsbuild](/guide/basic/configure-rsbuild) for more.

## Configuration Migration

In a webpack project, there might be some complex `webpack.config.js` configuration files.

After migrating to Rsbuild, most webpack configurations are built-in and do not require manual configuration, such as output, resolve, module.rules, etc.

For the few webpack configurations that need to be migrated, you can choose the following options:

- Use the [tools.rspack](/config/tools/rspack) option (Rspack and webpack configurations are basically equivalent).

```ts title="rsbuild.config.ts"
export default {
  tools: {
    rspack: {
      plugins: [new SomeWebpackPlugin()],
    },
  },
};
```

- Use encapsulated configs in Rsbuild, for example, options for css-loader can be set through [tools.cssLoader](/config/tools/css-loader).

> See [Configure Rspack](/guide/basic/configure-rspack) for more.

### Build Entry

webpack uses the `entry` field to set the build entry. In Rsbuild, you can use [source.entry](/config/source/entry) to set it.

```ts title="rsbuild.config.ts"
export default {
  source: {
    entry: {
      foo: './src/pages/foo/index.ts',
      bar: './src/pages/bar/index.ts',
    },
  },
};
```

### Cleaning Up Config

Since Rsbuild has built-in some common loaders and plugins, you can remove the following dependencies, which will significantly improve the dependency installation speed of the project:

- css-loader
- babel-loader
- style-loader
- postcss-loader
- html-webpack-plugin
- mini-css-extract-plugin
- autoprefixer
- @babel/core
- @babel/preset-env
- @babel/preset-typescript
- @babel/runtime
- ...

:::tip
The above only lists some of the common dependencies that can be removed. In actual webpack projects, there may be many other dependencies, please handle them as appropriate.
:::

### Using Plugins

Rsbuild offers a rich set of plugins that provide out-of-the-box support for common scenarios. You can refer to the [Plugin List](/plugins/list/index) documentation to learn about these plugins.

Taking a React project as an example, let's see how to integrate Rsbuild plugins. First, you can remove some React-related build dependencies that are already built into the Rsbuild React plugin, such as:

- `react-refresh`
- `@babel/preset-react`
- `@pmmmwh/react-refresh-webpack-plugin`

Then see the [React Plugin](/plugins/list/plugin-react) documentation, register it and use it as follows:

```diff
import { defineConfig } from '@rsbuild/core';
+import { pluginReact } from '@rsbuild/plugin-react';

export default {
+  plugins: [pluginReact()],
};
```

Most of the common webpack loaders and plugins can still be used in Rsbuild, but we recommend prioritizing the plugins provided by Rsbuild. This can further simplify your configuration. Below is their mapping relationship:

| webpack                                                                                        | Rsbuild                                                                                                         |
| ---------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| [@babel/preset-react](https://www.npmjs.com/package/@babel/preset-react)                       | [React Plugin](/plugins/list/plugin-react)                                                                      |
| [vue-loader](https://www.npmjs.com/package/vue-loader)                                         | [Vue Plugin](/plugins/list/plugin-vue) or [Vue 2 Plugin](https://github.com/rspack-contrib/rsbuild-plugin-vue2) |
| [svelte-loader](https://www.npmjs.com/package/svelte-loader)                                   | [Svelte Plugin](/plugins/list/plugin-svelte)                                                                    |
| [babel-preset-solid](https://www.npmjs.com/package/babel-preset-solid)                         | [Solid Plugin](/plugins/list/plugin-solid)                                                                      |
| [babel-loader](https://www.npmjs.com/package/babel-loader)                                     | [Babel Plugin](/plugins/list/plugin-babel)                                                                      |
| [sass-loader](https://www.npmjs.com/package/sass-loader)                                       | [Sass Plugin](/plugins/list/plugin-sass)                                                                        |
| [less-loader](https://www.npmjs.com/package/less-loader)                                       | [Less Plugin](/plugins/list/plugin-less)                                                                        |
| [stylus-loader](https://www.npmjs.com/package/stylus-loader)                                   | [Stylus Plugin](/plugins/list/plugin-stylus)                                                                    |
| [mdx-loader](https://www.npmjs.com/package/mdx-loader)                                         | [MDX Plugin](https://github.com/rspack-contrib/rsbuild-plugin-mdx)                                              |
| [pug-loader](https://www.npmjs.com/package/pug-loader)                                         | [Pug Plugin](https://github.com/rspack-contrib/rsbuild-plugin-pug)                                              |
| [yaml-loader](https://www.npmjs.com/package/yaml-loader)                                       | [Yaml Plugin](https://github.com/rspack-contrib/rsbuild-plugin-yaml)                                            |
| [toml-loader](https://www.npmjs.com/package/toml-loader)                                       | [Toml Plugin](https://github.com/rspack-contrib/rsbuild-plugin-toml)                                            |
| [@svgr/webpack](https://www.npmjs.com/package/@svgr/webpack)                                   | [SVGR Plugin](/plugins/list/plugin-svgr)                                                                        |
| [fork-ts-checker-webpack-plugin](https://www.npmjs.com/package/fork-ts-checker-webpack-plugin) | [@rsbuild/plugin-type-check](https://github.com/rspack-contrib/rsbuild-plugin-type-check)                       |
| [node-polyfill-webpack-plugin](https://www.npmjs.com/package/node-polyfill-webpack-plugin)     | [Node Polyfill Plugin](https://github.com/rspack-contrib/rsbuild-plugin-node-polyfill)                          |
| [@vue/babel-plugin-jsx](https://www.npmjs.com/package/@vue/babel-plugin-jsx)                   | [Vue JSX Plugin](https://github.com/rspack-contrib/rsbuild-plugin-vue-jsx)                                      |
| [@vue/babel-preset-jsx](https://www.npmjs.com/package/@vue/babel-preset-jsx)                   | [Vue 2 JSX Plugin](https://github.com/rspack-contrib/rsbuild-plugin-vue2-jsx)                                   |
| [eslint-webpack-plugin](https://www.npmjs.com/package/eslint-webpack-plugin)                   | [ESLint Plugin](https://github.com/rspack-contrib/rsbuild-plugin-eslint)                                        |
| [babel-plugin-styled-components](https://www.npmjs.com/package/babel-plugin-styled-components) | [Styled Components Plugin](https://github.com/rsbuild-contrib/rsbuild-plugin-styled-components)                 |

### Configure Dev Server

Rsbuild does not support the use of Rspack's [devServer](https://rspack.dev/config/dev-server) config. Please refer to [Rspack Dev Server](/guide/basic/server#rspack-dev-server) for replacement.

## Validating Results

After completing the above steps, you have completed the basic migration from webpack to Rsbuild. You can now run the `npm run dev` command to try starting the dev server.

If you encounter any issues during the build process, please debug according to the error log, or check the webpack configuration to see if there are any necessary configurations that have not been migrated to Rsbuild.

## Contents Supplement

The current document only covers part of the migration process. If you find suitable content to add, feel free to contribute to the documentation via pull request 🤝.

> The documentation for rsbuild can be found in the [rsbuild/website](https://github.com/web-infra-dev/rsbuild/tree/main/website) directory.
